<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Create or update role mappings API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="security-api.html" title="Security APIs">
<link rel="prev" href="security-api-put-privileges.html" title="Create or update application privileges API">
<link rel="next" href="security-api-put-role.html" title="Create or update roles API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="security-api.html">Security APIs</a></span>
»
<span class="breadcrumb-node">Create or update role mappings API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="security-api-put-privileges.html">« Create or update application privileges API</a>
</span>
<span class="next">
<a href="security-api-put-role.html">Create or update roles API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-api-put-role-mapping"></a>Create or update role mappings API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Creates and updates role mappings.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /_security/role_mapping/&lt;name&gt;</code><br></p>
<p><code class="literal">PUT /_security/role_mapping/&lt;name&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
To use this API, you must have at least the <code class="literal">manage_security</code> cluster privilege.
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Role mappings define which roles are assigned to each user. Each mapping has
<em>rules</em> that identify users and a list of <em>roles</em> that are granted to those users.</p>
<p>The role mapping APIs are generally the preferred way to manage role mappings
rather than using <a href="/guide/en/elasticsearch/reference/7.7/mapping-roles.html#mapping-roles-file" class="ulink" target="_top">role mapping files</a>.
The create or update role mappings API cannot update role mappings that are defined
in role mapping files.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>This API does not create roles. Rather, it maps users to existing roles.
Roles can be created by using the <a class="xref" href="security-api-put-role.html" title="Create or update roles API">create or update
roles API</a> or <a class="xref" href="defining-roles.html#roles-management-file" title="File-based role management">roles files</a>.</p>
</div>
</div>
<p>For more information, see <a class="xref" href="mapping-roles.html" title="Mapping users and groups to roles">Mapping users and groups to roles</a>.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_role_templates"></a>Role templates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The most common use for role mappings is to create a mapping from a known value
on the user to a fixed role name. For example, all users in the
<code class="literal">cn=admin,dc=example,dc=com</code> LDAP group should be given the <code class="literal">superuser</code> role in
Elasticsearch. The <code class="literal">roles</code> field is used for this purpose.</p>
<p>For more complex needs, it is possible to use Mustache templates to dynamically
determine the names of the roles that should be granted to the user. The
<code class="literal">role_templates</code> field is used for this purpose.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>To use role templates successfully, the relevant scripting feature must be
enabled. Otherwise, all attempts to create a role mapping with role templates
fail. See <a class="xref" href="modules-scripting-security.html#allowed-script-types-setting" title="Allowed script types setting">Allowed script types setting</a>.</p>
</div>
</div>
<p>All of the <a class="xref" href="role-mapping-resources.html" title="Role mapping resources">user fields</a> that are available in the
role mapping <code class="literal">rules</code> are also available in the role templates. Thus it is possible
to assign a user to a role that reflects their <code class="literal">username</code>, their <code class="literal">groups</code>, or the
name of the <code class="literal">realm</code> to which they authenticated.</p>
<p>By default a template is evaluated to produce a single string that is the name
of the role which should be assigned to the user. If the <code class="literal">format</code> of the template
is set to <code class="literal">"json"</code> then the template is expected to produce a JSON string or an
array of JSON strings for the role names.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">name</code>
</span>
</dt>
<dd>
(string) The distinct name that identifies the role mapping. The name is
 used solely as an identifier to facilitate interaction via the API; it does
 not affect the behavior of the mapping in any way.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following parameters can be specified in the body of a PUT or POST request
and pertain to adding a role mapping:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">enabled</code>
</span>
</dt>
<dd>
(Required, boolean) Mappings that have <code class="literal">enabled</code> set to <code class="literal">false</code> are ignored when
role mapping is performed.
</dd>
<dt>
<span class="term">
<code class="literal">metadata</code>
</span>
</dt>
<dd>
(object) Additional metadata that helps define which roles are assigned to each
user. Within the <code class="literal">metadata</code> object, keys beginning with <code class="literal">_</code> are reserved for
system usage.
</dd>
<dt>
<span class="term">
<code class="literal">roles</code>
</span>
</dt>
<dd>
(list of strings) A list of role names that are granted to the users that match
the role mapping rules.
<em>Exactly one of <code class="literal">roles</code> or <code class="literal">role_templates</code> must be specified</em>.
</dd>
<dt>
<span class="term">
<code class="literal">role_templates</code>
</span>
</dt>
<dd>
(list of objects) A list of mustache templates that will be evaluated to
determine the roles names that should granted to the users that match the role
mapping rules.
The format of these objects is defined below.
<em>Exactly one of <code class="literal">roles</code> or <code class="literal">role_templates</code> must be specified</em>.
</dd>
<dt>
<span class="term">
<code class="literal">rules</code>
</span>
</dt>
<dd>
(Required, object) The rules that determine which users should be matched by the
mapping. A rule is a logical condition that is expressed by using a JSON DSL.
See  <a class="xref" href="role-mapping-resources.html" title="Role mapping resources">Role mapping resources</a>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-put-role-mapping-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following example assigns the "user" role to all users:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, <a id="CO652-1"></a><i class="conum" data-value="1"></i>
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { <a id="CO652-2"></a><i class="conum" data-value="2"></i>
    "version" : 1
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2068.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO652-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Mappings that have <code class="literal">enabled</code> set to <code class="literal">false</code> are ignored when role mapping
is performed.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO652-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Metadata is optional.</p>
</td>
</tr>
</table>
</div>
<p>A successful call returns a JSON structure that shows whether the mapping has
been created or updated.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "role_mapping" : {
    "created" : true <a id="CO653-1"></a><i class="conum" data-value="1"></i>
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO653-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>When an existing mapping is updated, <code class="literal">created</code> is set to false.</p>
</td>
</tr>
</table>
</div>
<p>The following example assigns the "user" and "admin" roles to specific users:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping2
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2069.console"></div>
<p>The following example matches users who authenticated against a specific realm:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping3
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2070.console"></div>
<p>The following example matches any user where either the username is <code class="literal">esadmin</code>
or the user is in the <code class="literal">cn=admin,dc=example,dc=com</code> group:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping4
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2071.console"></div>
<p>The example above is useful when the group names in your identity management
system (such as Active Directory, or a SAML Identity Provider) do not have a
1-to-1 correspondence with the names of roles in Elasticsearch. The role mapping is the
means by which you link a <em>group name</em> with a <em>role name</em>.</p>
<p>However, in rare cases the names of your groups may be an exact match for the
names of your Elasticsearch roles. This can be the case when your SAML Identity Provider
includes its own "group mapping" feature and can be configured to release Elasticsearch
role names in the user’s SAML attributes.</p>
<p>In these cases it is possible to use a template that treats the group names as
role names.</p>
<p><span class="strong strong"><strong>Note</strong></span>: This should only be done if you intend to define roles for all of the
provided groups. Mapping a user to a large number of unnecessary or undefined
roles is inefficient and can have a negative effect on system performance.
If you only need to map a subset of the groups, then you should do this
using explicit mappings.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping5
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, <a id="CO654-1"></a><i class="conum" data-value="1"></i>
      "format" : "json" <a id="CO654-2"></a><i class="conum" data-value="2"></i>
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2072.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO654-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">tojson</code> mustache function is used to convert the list of
group names into a valid JSON array.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO654-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Because the template produces a JSON array, the format must be
set to <code class="literal">json</code>.</p>
</td>
</tr>
</table>
</div>
<p>The following example matches users within a specific LDAP sub-tree:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping6
{
  "roles": [ "example-user" ],
  "enabled": true,
  "rules": {
    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2073.console"></div>
<p>The following example matches users within a particular LDAP sub-tree in a
specific realm:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping7
{
  "roles": [ "ldap-example-user" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
      { "field" : { "realm.name" : "ldap1" } }
    ]
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2074.console"></div>
<p>The rules can be more complex and include wildcard matching. For example, the
following mapping matches any user where <span class="strong strong"><strong>all</strong></span> of these conditions are met:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
the <em>Distinguished Name</em> matches the pattern <code class="literal">*,ou=admin,dc=example,dc=com</code>,
or the username is <code class="literal">es-admin</code>, or the username is <code class="literal">es-system</code>
</li>
<li class="listitem">
the user in in the <code class="literal">cn=people,dc=example,dc=com</code> group
</li>
<li class="listitem">
the user does not have a <code class="literal">terminated_date</code>
</li>
</ul>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping8
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "all": [
      {
        "any": [
          {
            "field": {
              "dn": "*,ou=admin,dc=example,dc=com"
            }
          },
          {
            "field": {
              "username": [ "es-admin", "es-system" ]
            }
          }
        ]
      },
      {
        "field": {
          "groups": "cn=people,dc=example,dc=com"
        }
      },
      {
        "except": {
          "field": {
            "metadata.terminated_date": null
          }
        }
      }
    ]
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2075.console"></div>
<p>A templated role can be used to automatically map every user to their own
custom role. The role itself can be defined through the
<a class="xref" href="security-api-put-role.html" title="Create or update roles API">Roles API</a> or using a
<a class="xref" href="custom-roles-authorization.html#implementing-custom-roles-provider" title="Implementing a custom roles provider">custom roles provider</a>.</p>
<p>In this example every user who authenticates using the "cloud-saml" realm
will be automatically mapped to two roles - the <code class="literal">"saml_user"</code> role and a
role that is their username prefixed with <code class="literal">_user_</code>.
As an example, the user <code class="literal">nwong</code> would be assigned the <code class="literal">saml_user</code> and
<code class="literal">_user_nwong</code> roles.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role_mapping/mapping9
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, <a id="CO655-1"></a><i class="conum" data-value="1"></i>
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2076.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO655-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Because it is not possible to specify both <code class="literal">roles</code> and <code class="literal">role_templates</code> in
the same role mapping, we can apply a "fixed name" role by using a template
that has no substitutions.</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="security-api-put-privileges.html">« Create or update application privileges API</a>
</span>
<span class="next">
<a href="security-api-put-role.html">Create or update roles API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
